ODDragAndDrop

Inside Macintosh: OpenDoc Class Reference /: Part 1 - Classes and Methods

ODDragAndDrop

Superclasses
ODObject
Subclasses
none

An object of the ODDragAndDrop class provides the mechanism for dragging and dropping objects within a part, between parts, between documents, and between an OpenDoc document and a non-OpenDoc application.

Description
The drag-and-drop facility of OpenDoc depends on system services provided by the platform. They include a service to allow data to be transferred within a process or between processes, and a systemwide mouse tracking service that can notify a process about the location and state of the mouse during a drag operation.
When a document is opened, the session object creates a single drag-and-drop object. All parts of that document share the drag-and-drop object; you can obtain a reference to it by calling the session object's GetDragAndDrop method (page 607). You must not cache this object; instead, you must call the session object's GetDragAndDrop method whenever you need the drag-and-drop object.
Data transfers requested by any part operate on the drag-and-drop object's content storage unit. You can obtain a reference to that storage unit by calling the drag-and-drop object's GetContentStorageUnit method (page 190). You must not cache that storage unit; instead you must call the GetContentStorageUnit method whenever you need to access the storage unit.
A drag initiated by an OpenDoc part moves or copies a single item, called a drag item. Some items that can be dragged are a content item, a text selection, or a selected embedded frame. A drag initiated by a non-OpenDoc application may have more than one drag item. For example, a drag initiated by an application that manipulates the file system (such as the Finder on the Mac OS platform) might include several files.
When your part receives a mouse-down event that occurred within an item that can be dragged, you can initiate a drag. Initiating a drag involves acquiring the drag-and-drop object from the session object, clearing the drag-and-drop object's content storage unit, copying data from the item to be dragged into the content storage unit, and starting a drag action. Once the drag is initiated, the drag-and-drop object notifies a facet when the mouse passes over it. If the mouse button is released over a facet, the facet calls its part's Drop method (page 506) to notify the part of the drop. The destination part can retrieve the dragged data, using the supplied drag-item iterator. A drag-item iterator is an object of the ODDragItemIterator class (page 198); it allows the part to iterate through the drag items and obtain a reference to the content storage unit for each one.
For more information on drag-and-drop operations, see the chapter on data transfer in the OpenDoc Programmer's Guide for the MacOS. For information on using a link specification to indicate that the source part can create a link, see the ODLinkSpec (page 390) class description.

Methods
This section presents summary descriptions of the ODDragAndDrop methods grouped according to purpose, followed by detailed descriptions in alphabetical order. Methods marked [M] are specific to the Mac OS platform.
Initiating a Drag

Clear
Clears the content storage unit for this drag-and-drop object.
StartDrag
Initiates a drag operation.
GetContentStorageUnit
Returns a reference to the content storage unit for this drag-and-drop object.
Drag Information

GetDragAttributes
Returns additional information about the current drag-and-drop operation.
GetDragReference [M]
Returns the Mac OS Drag Manager drag-reference number associated with the current drag operation.
User Interaction at Drop

ShowPasteAsDialog [M]
Displays the Paste As dialog box and sets the appropriate dialog items according to the input parameters.

Methods
Clear
StartDrag
GetContentStorageUnit
GetDragAttributes
GetDragReference
ShowPasteAsDialog